<!DOCTYPE html>

<html>

  <head>
    <title>Underactuated Robotics: Drake</title>
    <meta name="Underactuated Robotics: Drake" content="text/html; charset=utf-8;" />
    <link rel="canonical" href="http://underactuated.mit.edu/drake.html" />

    <script src="https://hypothes.is/embed.js" async></script>
    <script type="text/javascript" src="htmlbook/book.js"></script>

    <script src="htmlbook/mathjax-config.js" defer></script> 
    <script type="text/javascript" id="MathJax-script" defer
      src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-chtml.js">
    </script>
    <script>window.MathJax || document.write('<script type="text/javascript" src="htmlbook/MathJax/es5/tex-chtml.js" defer><\/script>')</script>

    <link rel="stylesheet" href="htmlbook/highlight/styles/default.css">
    <script src="htmlbook/highlight/highlight.pack.js"></script> <!-- http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html#language-names-and-aliases -->
    <script>hljs.initHighlightingOnLoad();</script>

    <link rel="stylesheet" type="text/css" href="htmlbook/book.css" />
  </head>

<body onload="loadChapter('underactuated');">

<div data-type="titlepage">
  <header>
    <h1><a href="index.html" style="text-decoration:none;">Underactuated Robotics</a></h1>
    <p data-type="subtitle">Algorithms for Walking, Running, Swimming, Flying, and Manipulation</p> 
    <p style="font-size: 18px;"><a href="http://people.csail.mit.edu/russt/">Russ Tedrake</a></p>
    <p style="font-size: 14px; text-align: right;"> 
      &copy; Russ Tedrake, 2020<br/>
      <a href="tocite.html">How to cite these notes</a> &nbsp; | &nbsp;
      <a target="_blank" href="https://docs.google.com/forms/d/e/1FAIpQLSesAhROfLRfexrRFebHWLtRpjhqtb8k_iEagWMkvc7xau08iQ/viewform?usp=sf_link">Send me your feedback</a><br/>
    </p>
  </header>
</div>

<p><b>Note:</b> These are working notes used for <a
href="http://underactuated.csail.mit.edu/Spring2020/">a course being taught
at MIT</a>. They will be updated throughout the Spring 2020 semester.  <a 
href="https://www.youtube.com/channel/UChfUOAhz7ynELF-s_1LPpWg">Lecture  videos are available on YouTube</a>.</p> 

<table style="width:100%;"><tr style="width:100%">
  <td style="width:33%;text-align:left;"><a class="previous_chapter" href=rl_policy_search.html>Previous Chapter</a></td>
  <td style="width:33%;text-align:center;"><a href=index.html>Table of contents</a></td>
  <td style="width:33%;text-align:right;"><a class="next_chapter" href=multibody.html>Next Chapter</a></td>
</tr></table>


<!-- EVERYTHING ABOVE THIS LINE IS OVERWRITTEN BY THE INSTALL SCRIPT -->
<chapter class="appendix" style="counter-reset: chapter 0"><h1>Drake</h1>

  <p><drake></drake> is the main software toolbox that we use for this text,
  which in fact originated in a large part due to the MIT underactuated course.
  The <drake></drake> website is the main source for information and
  documentation.  The goal of this chapter is to provide any additional
  information that can help you get up and running with the examples and
  exercises provided in these notes.</p>

  <section><h1>Pydrake</h1>

    <p><drake></drake> is primarily a C++ library, with rigorous coding
    standards and a maturity level intended to support even professional
    applications in industry.  In order to provide a gentler introduction, and
    to facilitate rapid prototyping, I've written these notes exclusively in
    python, using Drake's python bindings (pydrake).  These bindings are less
    mature than the C++ backend; your feedback (and even contributions) are very
    welcome. It is still improving rapidly.</p>

    <p>In particular, while the C++ API documentation is excellent, the autogenerated python docs are still a work in progress.  I currently recommend using the <a href="https://drake.mit.edu/doxygen_cxx/">C++ documentation</a> to find what you need, then checking the <a href="https://drake.mit.edu/pydrake/">Python documentation</a> only if you need to understand how the class or method is spelled in pydrake.</p>

    <p>There are also a number of <a href="https://nbviewer.jupyter.org/github/RobotLocomotion/drake/tree/master/tutorials/">tutorials</a> in <drake></drake> that can help you get started.</p>

  </section>

  <section><h1>Online Jupyter Notebooks</h1>

    <p>I will provide nearly all examples and exercises in the form of a <a
    href="http://jupyter.org/">Jupyter Notebook</a> so that we can leverage the
    fantastic and relatively recent availability of (free) cloud resources.
    There are a number of examples throughout the text (listed below) which will
    help you load the notebooks in the cloud, allowing you to do some
    sophisticated computation without installing anything on your machine!
    Links to the code will look like this:</p>

    <jupyter>examples/double_pendulum/dynamics.ipynb</jupyter>

    <p>You'll notice that we often provide links to <i>both</i> Google's Colaboratory and Binder, because they both have some advantages and disadvantages.</p>

    <p><b>Google's Colaboratory</b> is a fantastic resource, with generous
    computational resources and a very convenient interface that allows you to
    save/load your work on Google Drive.  At present, there are two major
    downsides to Colab: <ol> <li>It does not support interactive plots
    (specifically the <code>matplotlib notebook</code> backend).  For
    interactive graphics, we have to <a href="https://mybinder.org/v2/gh/RobotLocomotion/drake/master?filepath=tutorials/mathematical_program.ipynb">record an animation, and convert it to an
    html compatible format.</a> But the time/memory that these operations require often exceeds the actual simulation time and make
    the experience significantly less interactive.</li> <li>We cannot provision
    the machines ahead of time.  We have a slightly ugly install script at the
    top of every notebook, and the first time you open each notebook it takes
    about two minutes to provision the machine.  At the time of this writing, it
    seems that the machine will stay provisioned for you <a
    href="https://stackoverflow.com/questions/54057011/google-colab-session-timeout">for
    90 minutes if you close the browser, or 12 hours if you keep it open.</a>
    Provisioning is per user and appears relatively unlimited.</li></ol></p>

    <p><b>Binder</b> is another great resource, which we can configure to provision directly from a Docker instance.  It appears to provision itself by project -- once one of us starts a Binder instance for an example, it should load more quickly for the rest of us.  It <i>does</i> support the <code>matplotlib notebook</code> backend, so can provide a nicer user experience.  But Binder has some potentially painful limitations -- it seems that <a href="https://mybinder.readthedocs.io/en/latest/about/about.html#how-long-will-my-binder-session-last">all modifications to your notebook are lost after 10 minutes of inactivity</a>, and there is a <a href="https://mybinder.readthedocs.io/en/latest/about/user-guidelines.html#maximum-concurrent-users-for-a-repository">limit on the number of simultaneous users</a>.</p>

    <p>As a general rule, I would favor Binder for quick explorations and use it for many of the examples in the notes, but recommend Colab (or running on your own machine) if you intend to build on any of the examples or do any of the exercises.  Please use Colab if you are taking the course and planning to submit your assignment for credit.  For some examples, where I think the code runs only (or simply much better) on some platforms than others, I have removed the less appealing link(s).</p>

  </section>

  <section><h1>Running on your own machine</h1>

    <p>As you get more advanced, you will want to run (and extend) these examples on your own machine.  The <drake></drake> website has a number of <a href="https://drake.mit.edu/installation.html">installation options</a>, including precompiled binaries and Docker instances.  Here I provide an example workflow of setting up drake from the precompiled binaries and running the textbook examples.</p>

    <p>First, pick your platform (click on your OS):</p>

    <p style="text-align:center">
    <span class="bionic">
      <b>Ubuntu Linux (Bionic)</b>  |
      <span onclick="setPlatform('mac');" style="text-decoration:underline;cursor:pointer">Mac Homebrew</span>
    </span>
    <span class="mac">
      <span onclick="setPlatform('bionic');"
            style="text-decoration:underline;cursor:pointer">Ubuntu Linux
        (Bionic)</span>  |
      <b>Mac Homebrew</b> </span></p>

    <subsection><h1>Install Drake</h1>

      <p>The links below indicate the specific distributions that the
      examples in this text have been tested against.</p>

      <h4 >Download the binaries</h4>

      <div class="bionic"><pre class="highlight"><code>curl -o drake.tar.gz <div id="drake-bionic-binaries" style="display:inline">https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-bionic.tar.gz</div></code></pre></div>

      <div class="mac"><pre class="highlight"><code>curl -o drake.tar.gz <div id="drake-mac-binaries" style="display:inline">https://drake-packages.csail.mit.edu/drake/nightly/drake-latest-mac.tar.gz</div></code></pre></div>

      <h4>Unpack and set your PYTHONPATH and Test</h4>

      <div class="bionic"><pre class="highlight"><code>sudo tar -xvzf drake.tar.gz -C /opt
sudo /opt/drake/share/drake/setup/install_prereqs.sh
export PYTHONPATH=/opt/drake/lib/python3.6/site-packages:${PYTHONPATH}

python3 -c 'import pydrake; print(pydrake.__file__)</code></pre></div>

      <div class="mac"><pre class="highlight"><code>sudo tar -xvzf drake.tar.gz -C /opt
/opt/drake/share/drake/setup/install_prereqs.sh
export PYTHONPATH=/opt/drake/lib/python3.8/site-packages:${PYTHONPATH}
export PATH=/usr/local/opt/python@3.8/bin:${PATH}

python3 -c 'import pydrake; print(pydrake.__file__)</code></pre></div>

    </section>

    <subsection><h1>Download the textbook supplement</h1>

      <div><pre class="highlight"><code>git clone https://github.com/RussTedrake/underactuated.git</code></pre></div>

      <p>and install the prerequisites using the platform-specific installation script provided:</p>

      <div class="bionic"><pre class="highlight"><code>cd underactuated
sudo scripts/setup/ubuntu/18.04/install_prereqs.sh
pip3 install --requirement requirements.txt
export PYTHONPATH=`pwd`:${PYTHONPATH}</code></pre></div>

      <div class="mac"><pre class="highlight"><code>cd underactuated
scripts/setup/mac/install_prereqs.sh
pip3 install --requirement requirements.txt /opt/drake/share/drake/setup/requirements.txt
export PYTHONPATH=`pwd`:${PYTHONPATH}</code></pre></div>

<p>Note that, as always, I would strongly recommend running
  <code>pip</code>
  commands in a <a
  href="https://python-guide-cn.readthedocs.io/en/latest/dev/virtualenvs.html">virtualenv</a>.</p>

    </subsection>

    <subsection><h1>Run Jupyter Notebook</h1>

      <div><pre class="highlight"><code>cd underactuated
jupyter notebook</code></pre></div>

      <p>You will find the examples in the <code>examples</code> subdirectory, and the notebook exercises in the <code>exercises</code> subdirectory.  You might try opening <code>examples/double_pendulum/dynamics.ipynb</code> to get started.  Have fun!</p>

    </subsection>

  </section>

  <section><h1>Getting help</h1>

    <p>If you have trouble with <drake></drake>, please follow the advice <a href="https://drake.mit.edu/getting_help.html">here</a>.  If you have trouble with the underactuated repo, you can check for known issues (and potentially file a new one) <a href="https://github.com/RussTedrake/underactuated/issues">here</a>.</p>

  </section>

    <div style="height:30px"></div>

</chapter>
<!-- EVERYTHING BELOW THIS LINE IS OVERWRITTEN BY THE INSTALL SCRIPT -->

<table style="width:100%;"><tr style="width:100%">
  <td style="width:33%;text-align:left;"><a class="previous_chapter" href=rl_policy_search.html>Previous Chapter</a></td>
  <td style="width:33%;text-align:center;"><a href=index.html>Table of contents</a></td>
  <td style="width:33%;text-align:right;"><a class="next_chapter" href=multibody.html>Next Chapter</a></td>
</tr></table>

<div id="footer">
  <hr>
  <table style="width:100%;">
    <tr><td><a href="https://accessibility.mit.edu/">Accessibility</a></td><td style="text-align:right">&copy; Russ
      Tedrake, 2020</td></tr>
  </table>
</div>


</body>
</html>
